Skip to content

docs(agents): pin the base SHA and lease exactly when working in parallel worktrees - #8804

Open
bokelley wants to merge 1 commit into
mainfrom
docs/agents-parallel-worktrees
Open

bokelley wants to merge 1 commit into
mainfrom
docs/agents-parallel-worktrees

Conversation

@bokelley

@bokelley bokelley commented Nov 8, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a short Parallel worktrees subsection to .agents/playbook.md, under "Local Hooks". Git worktrees isolate the working tree, index and HEAD, but they share the object store, every ref (including origin/*) and the stash. So one session's git fetch moves origin/main under every other worktree of the same clone.

The rule it adds:

  • Resolve the base SHA once, after the first fetch, and use that SHA for rebase, diff and test baselines. Never re-resolve origin/main mid-task.
  • Force-push with an exact lease, --force-with-lease=<branch>:<expected-sha>. A bare lease compares against the shared origin/<branch>.
  • Never use bare git stash / git stash pop. Prefer a WIP commit, or a tagged stash restored by SHA.

Why

On 2026-11-08 a session rebasing #8512 re-resolved origin/main partway through its task. Another session's fetch had just moved it to #8798, so the commit landed on top of #8798 and would have reverted three of its files. The session caught it before pushing. Several agents now work in parallel worktrees of one clone, so this will recur without a written rule.

Notes

  • Agent-tooling docs only. No protocol surface, so no changeset; check-changeset-protocol-scope passes.
  • .agents/** is a sensitive path, so it needs a human merge.

🤖 Generated with Claude Code

…llel worktrees

Worktrees share refs (including origin/*) and the stash across sessions,
so a fetch in one worktree moves origin/main under the others. Record the
rule: pin the base SHA once, push with an exact-SHA lease, never use a
bare git stash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Escalate to human review

Escalate — gated path requires human/CODEOWNERS approval.

This PR modifies .agents/playbook.md, which matches the gated-path glob .agents/** (gated_paths: true), and review_decision is REVIEW_REQUIRED — not APPROVED. Per decision rule row 2, this is a hard, non-overridable approval gate: the outcome cannot be approve or plain comment until a real human/CODEOWNERS approval lands.

The diff itself is clean: a single docs-only change adding a "Parallel worktrees" section (20 additions, one file). The reviewer verified the technical claims and found no Critical/High/Medium findings. No protocol surface, schema, wire, or changeset implications. Absent the gated-path gate this would approve — but the gate is unsatisfied.

Escalation reasons

  • .agents/playbook.md is under the .agents/** hard approval gate; requires human/CODEOWNERS review (review_decision is REVIEW_REQUIRED, not APPROVED).

Why human review

  • Modifies .agents/playbook.md which matches the gated path .agents/**; human/CODEOWNERS approval required (review_decision is REVIEW_REQUIRED, not APPROVED).
  • This PR touches a path under a hard, non-overridable approval gate (.agents/playbook.md (modified) matches .agents/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

@aao-secretariat aao-secretariat Bot added the ladon/needs-human-review Ladon has escalated this PR for human review. label Nov 8, 2026
@bokelley
bokelley enabled auto-merge (squash) November 8, 2026 15:47
bokelley added a commit that referenced this pull request Nov 8, 2026
…tail

main now locks @contentauth/c2pa-node 0.10.0, whose postinstall.cjs is
byte-identical to 0.9.7's and whose Cargo manifest still inherits workspace
fields. Adds 0.10.0 to the version matrix and mixed-version pairs, and a
fixture with the verbatim unhandled-rejection tail npm printed after the
signature in #8804's failed install, which must still retry once.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ladon/needs-human-review Ladon has escalated this PR for human review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant